home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1997 January / macformat46.iso / Shareware Plus / Developers / Library / Grant's CGI Framework / Grant's CGI Framework / grantscgi / Util / CGI.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-09-23  |  12.5 KB  |  455 lines
  1. #pragma once
  2. /*****
  3.  *
  4.  *    Grant's CGI Framework
  5.  *
  6.  *    CGI.h
  7.  *
  8.  *    standard types and function prototypes for cgi applications
  9.  *    See the Read Me or CGI.c for instructions on using the CGI Utilities
  10.  *
  11.  *    #include this file in your source files that need to access the cgi module
  12.  *
  13.  *    This is a support file for "Grant's CGI Framework".
  14.  *    Please see the license agreement that accompanies the distribution package
  15.  *    for licensing details.
  16.  *
  17.  *    Copyright ©1995,1996 by Grant Neufeld
  18.  *
  19.  *    http://arpp.carleton.ca/cgi/framework/
  20.  *    gneufeld@ccs.carleton.ca
  21.  *    grant@acm.org
  22.  *
  23.  *****/
  24.  
  25. #include "MyConfiguration.h"
  26. #if kCompileWithCGICode
  27.  
  28. #include <Threads.h>
  29. #if kCompilingForWSAPI
  30. #include <WSAPI.h>
  31. #else
  32. #include "MemoryUtil.h"
  33. #endif
  34.  
  35.  
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif
  39.  
  40.  
  41. /***  CONSTANT DECLARATIONS  ***/
  42.  
  43. #define kCGIHTTPMethodGet                "GET"
  44. #define kCGIHTTPMethodPost                "POST"
  45. #define kCGIHTTPMethodGetConditional    "GET_CONDITIONAL"
  46. #define kCGIHTTPMethodConditionalGet    "CONDITIONAL_GET"
  47.  
  48. #define kCGIFormFieldDelimiter    '='
  49. #define kCGIFormFieldSeparator    '&'
  50.  
  51. /* Apple events */
  52.  
  53. enum {
  54.     kAEClassCGI                = 'WWWΩ',
  55.     kAEIDSearchDoc            = 'sdoc',
  56.  
  57.     /* CGI event parameters */
  58.     kCGIpath_args            = '----',
  59.     kCGIhttp_search_args    = 'kfor',
  60.     kCGIusername            = 'user',
  61.     kCGIpassword            = 'pass',
  62.     kCGIfrom_user            = 'frmu',
  63.     kCGIclient_address        = 'addr',
  64.     kCGIpost_args            = 'post',
  65.     kCGImethod                = 'meth',
  66.     kCGIserver_name            = 'svnm',
  67.     kCGIserver_port            = 'svpt',
  68.     kCGIscript_name            = 'scnm',
  69.     kCGIcontent_type        = 'ctyp',
  70.     kCGIcontent_length        = 'CLen',
  71.     kCGIreferer                = 'refr',
  72.     kCGIuser_agent            = 'Agnt',
  73.     kCGIaction                = 'Kact',
  74.     kCGIaction_path            = 'Kapt',
  75.     kCGIclient_ip            = 'Kcip',
  76.     kCGIfull_request        = 'Kfrq',
  77.     kCGIversion                = 'Pvrs',
  78.     kCGIconnection            = 'Kcid'
  79. };
  80.  
  81. /* for an official listing of the maximum sizes for CGI parameters,
  82.     <http://www.biap.com/datapig/mrwheat/cgi_params.html> */
  83. enum {
  84.     kCGIParamMaxSize        = 32769,
  85.  
  86.     kCGIMaxpath_args        = 1024,
  87.     kCGIMaxhttp_search_args    = 1024,
  88.     kCGIMaxusername            = 32,
  89.     kCGIMaxpassword            = 32,
  90.     kCGIMaxfrom_user        = 128,
  91.     kCGIMaxclient_address    = 256,
  92.     kCGIMaxpost_args        = 32768,
  93.     kCGIMaxmethod            = 32,
  94.     kCGIMaxserver_name        = 256,
  95.     kCGIMaxserver_port        = 16,
  96.     kCGIMaxscript_name        = 1024,
  97.     kCGIMaxcontent_type        = 64,
  98.     kCGIMaxreferer            = 1024,
  99.     kCGIMaxuser_agent        = 256,
  100.     kCGIMaxaction            = 32,
  101.     kCGIMaxaction_path        = 1024,
  102.     kCGIMaxclient_ip        = 32,
  103.     kCGIMaxfull_request        = 4096,
  104.     kCGIMaxconnection        = 4
  105. };
  106.  
  107. /* Action Names */
  108. #define kCGIActionNameCGI            "CGI"
  109. #define kCGIActionNameACGI            "ACGI"
  110. #define kCGIActionNamePreProcessor    "PREPROCESSOR"
  111. #define kCGIActionNamePostProcessor    "POSTPROCESSOR"
  112. #define kCGIActionNameLogging        "LOGGING"
  113. #define kCGIActionNameSecurity        "SECURITY"
  114. #define kCGIActionNameError            "ERROR"
  115. #define kCGIActionNameNoAccess        "NOACCESS"
  116. #define kCGIActionNameIndex            "INDEX"
  117.  
  118. /* Send Partial event */
  119.  
  120. enum {
  121.     kMyAESendPartial        = 'SPar',
  122.  
  123.     kCGIPartialData            = '----',
  124.     kConnectionIDKeyword    = 'Kcid',
  125.     kMoreKeyword            = 'Kmor'
  126. };
  127.  
  128. #define kCGIPartialStartString    "<SEND_PARTIAL>"
  129.  
  130.  
  131. /***  TYPE DECLARATIONS  ***/
  132.  
  133. #if kCompileWithCGIFormHandling
  134. typedef struct
  135. {
  136.     char *    name;
  137.     char *    value;
  138. } CGIFormField;
  139. #endif
  140.  
  141. #if kCompileWithCGImethod
  142. typedef enum
  143. {
  144.     HTTP_UNDEFINED    = 0,
  145.     HTTP_get,
  146.     HTTP_post,
  147.     HTTP_getConditional
  148. } HTTPMethod;
  149. #endif
  150.  
  151. #if kCompilingForWSAPI || kCompileWithCGIActionSupport
  152. typedef enum {
  153.     #ifndef WSAPI_Run_Role
  154.     CGIRole_CGI                = 0,    /* CGI or ACGI (difference only affects server, not CGI) */
  155.     CGIRole_PreProcessor    = 1,
  156.     CGIRole_PostProcessor    = 2,
  157.     CGIRole_Logging            = 3,    /* receiving log info */
  158.     CGIRole_Security        = 4,    /* access restriction control */
  159.     CGIRole_Error            = 5,    /* invalid url handling */
  160.     CGIRole_NoAccess        = 6,    /* client IP or domain denied access */
  161.     CGIRole_Index            = 7        /* default file ('/') */
  162.     #else
  163.     CGIRole_CGI                = WSAPI_CGI_Role,
  164.     CGIRole_PreProcessor    = WSAPI_PreProcessor_Role,
  165.     CGIRole_PostProcessor    = WSAPI_PostProcessor_Role,
  166.     CGIRole_Logging            = WSAPI_Logging_Role,
  167.     CGIRole_Security        = WSAPI_Security_Role,
  168.     CGIRole_Error            = WSAPI_Error_Role,
  169.     CGIRole_NoAccess        = WSAPI_NoAccess_Role,
  170.     CGIRole_Index            = WSAPI_Index_Role
  171.     #endif
  172. } CGIRole;
  173. #endif
  174.  
  175.  
  176. typedef struct
  177. {
  178.     #if kCompilingForWSAPI
  179.     /* The WSAPI data structure associated with the CGI event.
  180.         This must be the first item in the structure! */
  181.     WSAPI_CommandPBPtr    wsapi;
  182.     #endif
  183.     
  184.     /** PUBLIC, READ-ONLY (don't modify these fields in your code) **/
  185.     
  186.     #if kCompileWithCGIpath_args
  187.     char *        path_args;            /* '----' path_args            */
  188.     #endif
  189.     #if kCompileWithCGIhttp_search_args
  190.     char *        http_search_args;    /* 'kfor' http_search_args    */
  191.     #endif
  192.     #if kCompileWithCGIusername
  193.     char    username[kCGIMaxusername];    /* 'user' username            */
  194.     #endif
  195.     #if kCompileWithCGIpassword
  196.     char    password[kCGIMaxpassword];    /* 'pass' password            */
  197.     #endif
  198.     #if kCompileWithCGIfrom_user
  199.     char    from_user[kCGIMaxfrom_user];/* 'frmu' from_user            */
  200.     #endif
  201.     #if kCompileWithCGIclient_address
  202.     char    client_address[kCGIMaxclient_address];/* 'addr' client_address    */
  203.     #endif
  204.     #if kCompileWithCGIpost_args
  205.     char *        post_args;            /* 'post' post_args            */
  206.     #endif
  207.     #if kCompileWithCGImethod
  208.     HTTPMethod    method;                /* 'meth' method            */
  209.     #endif
  210.     #if kCompileWithCGIserver_name
  211.     char    server_name[kCGIMaxserver_name];/* 'svnm' server_name        */
  212.     #endif
  213.     #if kCompileWithCGIserver_port
  214.     short        server_port;        /* 'svpt' server_port        */
  215.     #endif
  216.     #if kCompileWithCGIscript_name
  217.     char *        script_name;        /* 'scnm' script_name        */
  218.     #endif
  219.     #if kCompileWithCGIcontent_type
  220.     char    content_type[kCGIMaxcontent_type];/* 'ctyp' content_type        */
  221.     #endif
  222.     #if kCompileWithCGIcontent_length
  223.     unsigned long    content_length;/* 'CLen' content_type        */
  224.     #endif
  225.     #if kCompileWithCGIreferer
  226.     char *        referer;            /* 'refr' referer            */
  227.     #endif
  228.     #if kCompileWithCGIuser_agent
  229.     char    user_agent[kCGIMaxuser_agent];/* 'Agnt' user_agent        */
  230.     #endif
  231.     
  232.     #if kCompileWithCGIActionSupport
  233.     char    action[kCGIMaxaction];    /* 'Kact' action            */
  234.     char *    action_path;            /* 'Kapt' action_path        */
  235.     #endif
  236.     
  237.     #if kCompileWithCGIActionSupport || kCompilingForWSAPI
  238.     CGIRole    role;            /* the function that the CGI is being called to perform */
  239.     #endif
  240.     
  241.     #if kCompileWithCGIclient_ip
  242.     #if kCompilingForWSAPI
  243.     long    client_ip;                /* 'Kcip' client_ip        */
  244.     #else
  245.     char    client_ip[kCGIMaxclient_ip];    /* 'Kcip' client_ip        */
  246.     #endif
  247.     #endif
  248.     #if kCompileWithCGIfull_request
  249.     char *        full_request;        /* 'Kfrq' full_request        */
  250.     #endif
  251.     
  252.     #if kCompileWithCGISendPartial
  253.     long        connection;            /* 'Kcid' connection        */
  254.     #endif
  255.     
  256.     #if kCompilingForWSAPI
  257.     /* these fields are only available to WSAPI plug-ins */
  258.     
  259.     #if kCompileWithCGIfileMIMEType
  260.     /* The MIME type of the URL in piScriptName */
  261.     char *    fileMIMEType;    /* 'Mime' */
  262.     #endif
  263.     #if kCompileWithCGIserverField
  264.     /* The HTTP header field for this server. e.g., "Server: WebSTAR/1.3 ID/22" */
  265.     char *    serverField;    /* 'SvFd' */
  266.     #endif
  267.     #if kCompileWithCGIserverDirectoryPath
  268.     /* A C string representing the complete (machine-specific) path name of
  269.         the server's working directory */
  270.     char *    serverDirectoryPath;    /* 'SPth' */
  271.     #endif
  272.     #if kCompileWithCGIurlPhysicalPath
  273.     /* If the URL represents an actual file in the file system, this parameter
  274.         contains its name relative to the server's root. */
  275.     char *    urlPhysicalPath;    /* 'UPth' */
  276.     #endif
  277.     #if kCompileWithCGIifModifiedSince
  278.     /* short (really a Boolean). True if the file has been modified since
  279.         last retrieval or if modification cannot be determined.
  280.         False if unchanged. */
  281.     short    ifModifiedSince;    /* 'IfMS' */
  282.     #endif
  283.     #if kCompileWithCGIcurrentRealm
  284.     /* typeChar, 256 max. The realm (if any) that the requested URL belongs to.
  285.         WSAPI_E_RequestFailed will be returned by GetParameter
  286.         if this value isn't defined for the current request. */
  287.     char    currentRealm[256];    /* 'CRlm' */
  288.     #endif
  289.     
  290.     #endif /* kCompilingForWSAPI */
  291.     
  292.     #if kCompileWithCGIFormHandling
  293.     CGIFormField *    formFields;        /* the fields from form submission */
  294.     long            totalFields;    /* total number of fields    */
  295.     #endif
  296.     
  297.     
  298.     /** PRIVATE. these fields should not be touched outside the CGI.c file **/
  299.     
  300.     #if kCompilingForWSAPI
  301.     
  302.     /* this will be set to true if you return data on the connection from
  303.         within your custom code. */
  304.     Boolean        dataSent;            /* has data been sent yet? */
  305.     
  306.     #if kCompileWithTCPCode
  307.     WSAPI_Stream    tcpStream;
  308.     #endif
  309.     
  310.     #else /* not wsapi */
  311.     
  312.     AppleEvent        appleEvent;        /* originating appleEvent    */
  313.     AppleEvent        replyEvent;        /* apple event reply record    */
  314.     
  315.     #if kCompileWithThreadedAppleEvents
  316.     Boolean            suspended;        /* whether the AE has been suspended */
  317.     #endif
  318.     
  319.     #if kCompileWithCGISendPartial
  320.     char            sendPartialActive;    /* boolean - has send partial been used on this CGIRecord already */
  321.     char            sendPartialDone;    /* boolean - send partial connection has been closed (!sendMore sent) */
  322.     #endif
  323.     
  324.     #if kCompileWithTCPCode
  325.     //••• need to put in tcp support for applications, and not just plug-ins
  326.     #endif
  327.     
  328.     #endif /* !(kCompilingForWSAPI) */
  329.     
  330.     
  331.     /** PUBLIC, READ-WRITE. fields to be filled in **/
  332.     
  333.     #if kCompileWithCGIResponseDataAsHandle
  334.     Handle        responseData;        /* data to return to the client        */
  335.     #else
  336.     char *        responseData;        /* data to return to the client        */
  337.     #endif
  338.     long        responseSize;        /* size in bytes of the response    */
  339.     
  340.     #if kCompileWithCGIRefCon
  341.     long        refCon;                /* field for storing custom data    */
  342.     #endif
  343. } CGIrecord;
  344.  
  345. typedef CGIrecord ** CGIHdl;
  346.  
  347.  
  348. /***  GLOBAL DECLARATIONS  ***/
  349.  
  350. #ifdef __CGISegment__
  351. #define _GLOBAL_    
  352. #else
  353. #define _GLOBAL_    extern
  354. #endif
  355.  
  356. /* these are globals for holding the standard http headers.
  357.     One of the headers must be prepended to the data returned in the Apple Event */
  358.  
  359. _GLOBAL_    Str255    gHTTPHeaderOK;            /* use data returned after header    */
  360. _GLOBAL_    Str255    gHTTPHeaderRedirect;    /* redirect client to different url    */
  361. _GLOBAL_    Str255    gHTTPHeaderErr;            /* an application level error        */
  362. #if kCompileWithCGISendPartial
  363. _GLOBAL_    Str255    gHTTPHeaderPush;        /* multipart server push            */
  364. #endif
  365.  
  366. _GLOBAL_    long    gHTTPHeaderOKSize;
  367. _GLOBAL_    long    gHTTPHeaderRedirectSize;
  368. _GLOBAL_    long    gHTTPHeaderErrSize;
  369. #if kCompileWithCGISendPartial
  370. _GLOBAL_    long    gHTTPHeaderPushSize;
  371. #endif
  372.  
  373. #undef _GLOBAL_
  374.  
  375.  
  376. /***  FUNCTION PROTOTYPES  ***/
  377.  
  378.         SInt32        InitCGIUtil            ( void );
  379.         
  380. #if kCompileWithCGIFormHandling
  381. p_export CGIFormField *    CGIFormFieldsFromArgs    ( CGIHdl, char *, long *, short * );
  382. p_export CGIFormField *    CGIFormFieldsFindRecord    ( CGIHdl, const char * );
  383. p_export const char *    CGIFormFieldsFindValue    ( CGIHdl, const char * );
  384. #endif    /* kCompileWithCGIFormHandling */
  385.         
  386. #if kCompileWithCGIActionSupport
  387. p_export Boolean    CGIActionIsCGIorACGI    ( CGIHdl );
  388. #endif
  389.  
  390. p_export Boolean    CGIIsSecurePath            ( char * );
  391.  
  392. #if kCompileWithCGIfull_request
  393. p_export Boolean    CGIHostNameDifferent    ( CGIHdl, char *, short );
  394. #endif
  395.  
  396. p_export void        CGIDecodeURLChars    ( char * );
  397. p_export char *        CGIEncodeURLChars    ( CGIHdl, const char *, OSErr * );
  398. p_export Boolean    CGICharWillHex        ( unsigned char );
  399. p_export void        CGICharToHex        ( unsigned char, char * );
  400.         
  401. p_export void        CGIPathToMacPath    ( char * );
  402.  
  403. #if kCompilingForWSAPI
  404. p_export char *        CGIWSAPIGetParam        ( WSAPI_CommandPBPtr, WSAPI_ParamKeywords, void *, UInt32 );
  405. p_export void        CGIWSAPIUseMyResFile    ( void );
  406. p_export void        CGIWSAPIResetResFile    ( void );
  407. #else
  408. #define CGIWSAPIUseMyResFile()    
  409. #define CGIWSAPIResetResFile()    
  410. #endif
  411.  
  412. p_export OSErr        CGISendData            ( CGIHdl, void *, long, Boolean );
  413.  
  414. /* ••• This function is incomplete - don't use it!!! */
  415. p_export OSErr        CGIPassAppleEvent    ( CGIHdl, OSType );
  416.         
  417. p_export void        CGILogData            ( CGIHdl );
  418.  
  419. /* Memory Handling */
  420. #if kCompilingForWSAPI
  421.     /* special memory handling under WSAPI */
  422. p_export Handle        CGINewHandle        ( CGIHdl, long, OSErr * );
  423. p_export Handle        CGINewHandleClear    ( CGIHdl, long, OSErr * );
  424. p_export Ptr        CGINewPtr            ( CGIHdl, long, OSErr * );
  425. p_export Ptr        CGINewPtrClear        ( CGIHdl, long, OSErr * );
  426.  
  427. p_export void        CGIDisposeHandle    ( CGIHdl, Handle );
  428. p_export void        CGIDisposePtr        ( CGIHdl, Ptr );
  429. #else
  430.     /* wrappers for standard memory handling when not compiling under wsapi */
  431.     #define CGINewHandle(theCGIHdl,theSize,theErr)        MemoryNewHandle(theSize,theErr)
  432.     #define CGINewHandleClear(theCGIHdl,theSize,theErr)    MemoryNewHandleClear(theSize,theErr)
  433.     #define CGINewPtr(theCGIHdl,theSize,theErr)            MemoryNewPtr(theSize,theErr)
  434.     #define CGINewPtrClear(theCGIHdl,theSize,theErr)    MemoryNewPtrClear(theSize,theErr)
  435.  
  436.     #define CGIDisposeHandle(theCGIHdl,theHandle)        MemoryDisposeHandle(theHandle)
  437.     #define CGIDisposePtr(theCGIHdl,thePtr)                MemoryDisposePtr(thePtr)
  438. #endif
  439.  
  440.  
  441. #ifdef __cplusplus
  442. }
  443. #endif
  444.  
  445.  
  446. #else    /* if not kCompileWithCGICode */
  447.  
  448.     /* these are defined like this here so the StartupApplication function
  449.         doesn't have to be messed with when compiling without the CGI module */
  450.     #define InitCGIUtil()        (noErr)
  451.  
  452. #endif    /* kCompileWithCGICode */
  453.  
  454. /***  EOF  ***/
  455.